The 640 MEG Shareware Studio 2

home *** CD-ROM | disk | FTP | other *** search

/ The 640 MEG Shareware Studio 2 / The 640 Meg Shareware Studio CD-ROM Volume II (Data Express)(1993).ISO / utility / cron16.zip / CRON.DOC < prev next >

Wrap

Text File | 1991-01-20 | 63KB | 1,986 lines

CRON User's Guide Manual Revision 01-20-91 CRON Version 1.6 Shareware by Tron Hvaring PO Box 371 N-8501 Narvik Norway Phone: +47 82 44145 Fax: +47 82 44 160 BIXname: thvaring CRON User's Guide Rev. 01-20-91 (C) 1991 Tron Hvaring CRON User's Guide Rev. 01-20-91 Contents-1 TABLE OF CONTENTS 1 INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.1 Product Description . . . . . . . . . . . . . . . . . . . . 1 1.2 Shareware . . . . . . . . . . . . . . . . . . . . . . . . . 2 1.3 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 2 1.4 System Requirements . . . . . . . . . . . . . . . . . . . . 2 1.5 Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . 2 2 INSTALLATION . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.1 Archive Contents . . . . . . . . . . . . . . . . . . . . . . 3 2.2 Installing CRON . . . . . . . . . . . . . . . . . . . . . . 3 2.3 Setting up CRON's environment . . . . . . . . . . . . . . . 3 2.4 Set Your Clock . . . . . . . . . . . . . . . . . . . . . . . 4 3 USING CRON . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3.1 Command-line Summary . . . . . . . . . . . . . . . . . . . . 5 3.2 Crontab override -- the '-c tab' option . . . . . . . . . . 5 3.3 Disable logging -- the '-n' option . . . . . . . . . . . . . 6 3.4 Swap Mode -- the '-s', '-d dir' and '-e' options . . . . . . 6 3.5 Verbose mode -- the '-v' option . . . . . . . . . . . . . . 6 3.6 Locking the logfile -- the '-L' and '-l' option . . . . . . 7 3.7 Stopping CRON . . . . . . . . . . . . . . . . . . . . . . . 7 3.8 Startup Information . . . . . . . . . . . . . . . . . . . . 7 4 THE CRONTAB IN DETAIL . . . . . . . . . . . . . . . . . . . . . 8 4.1 Syntax Summary . . . . . . . . . . . . . . . . . . . . . . . 8 4.2 The Date and Time fields . . . . . . . . . . . . . . . . . . 8 4.3 The Command Field . . . . . . . . . . . . . . . . . . . . . 9 5 THE CRONLOG IN DETAIL . . . . . . . . . . . . . . . . . . . . . 12 5.1 General Description . . . . . . . . . . . . . . . . . . . . 12 5.2 Starting And Stopping CRON . . . . . . . . . . . . . . . . . 12 5.3 Start and Stop of CRONTAB Entry Processing . . . . . . . . . 13 5.4 Logging Multi-Command Execution . . . . . . . . . . . . . . 14 6 ERROR HANDLING . . . . . . . . . . . . . . . . . . . . . . . . . 15 6.1 General Considerations . . . . . . . . . . . . . . . . . . . 15 6.2 Failure to Spawn a Command . . . . . . . . . . . . . . . . . 16 6.3 A Spawned Command Fails . . . . . . . . . . . . . . . . . . 16 6.4 Other Internal CRON errors . . . . . . . . . . . . . . . . . 17 6.5 Exit Codes and COMMAND.COM . . . . . . . . . . . . . . . . . 17 7 ADVANCED TOPICS . . . . . . . . . . . . . . . . . . . . . . . . 18 7.1 Resource Requirements . . . . . . . . . . . . . . . . . . . 18 7.2 Using CRON with DESQview . . . . . . . . . . . . . . . . . . 18 7.3 CRON Technical Information . . . . . . . . . . . . . . . . . 19 7.4 Differences between CRON and UNIX cron . . . . . . . . . . . 19 7.5 CRONDV.EXE . . . . . . . . . . . . . . . . . . . . . . . . . 21 7.5.1 What Is CRONDV.EXE? . . . . . . . . . . . . . . . . . 21 7.5.2 How it Works . . . . . . . . . . . . . . . . . . . . 21 CRON User's Guide Rev. 01-20-91 (C) 1991 Tron Hvaring CRON User's Guide Rev. 01-20-91 Contents-2 7.5.3 The CRONPIF Environment Variable . . . . . . . . . . 21 7.5.4 CRONLOG entries . . . . . . . . . . . . . . . . . . . 22 7.5.5 About Programs spawned by CRONDV . . . . . . . . . . 22 7.5.6 Command-line Options . . . . . . . . . . . . . . . . 22 8 REFERENCE SECTION . . . . . . . . . . . . . . . . . . . . . . . 23 8.1 Error Messages . . . . . . . . . . . . . . . . . . . . . . . 23 8.2 Exit Codes . . . . . . . . . . . . . . . . . . . . . . . . . 24 8.2.1 Common Exit Codes . . . . . . . . . . . . . . . . . . 24 8.2.2 Swap Mode . . . . . . . . . . . . . . . . . . . . . . 25 8.2.3 Non-Swap Mode . . . . . . . . . . . . . . . . . . . . 25 8.2.4 RC = -1 for '!' Commands . . . . . . . . . . . . . . 25 9 UTILITY PROGRAMS . . . . . . . . . . . . . . . . . . . . . . . . 26 9.1 CDD.EXE . . . . . . . . . . . . . . . . . . . . . . . . . . 26 9.2 LOGCHECK.EXE . . . . . . . . . . . . . . . . . . . . . . . . 26 10 PROGRAM HISTORY . . . . . . . . . . . . . . . . . . . . . . . . . 28 CRON User's Guide Rev. 01-20-91 (C) 1991 Tron Hvaring CRON User's Guide Rev. 01-20-91 Page 1 1 INTRODUCTION 1.1 Product Description This is version 1.6 of CRON. CRON is a timed command dispatcher that closely implements all the features of the UNIX 'cron' utility that make sense in a DOS environment. CRON reads a special file at startup, conventionally called CRONTAB, where each entry defines a time and a command to execute at that time. All commands are periodic, i.e. one-shot commands are not possible. The longest period is one year, however, so this is not considered a problem. In a PC environment, a command with a 1-year period is a one- shot command for all practical purposes. After a command has executed, CRON re-calculates its next execution time, then sorts the command list in time order and waits until the first command in the list is due for execution. This sequence is repeated undefinitely (or until the user stops CRON). CRON optionally logs its activites in a file conventionally called CRONLOG. The layout of this file is more or less identical to the UNIX cronlog and conveys the same information. The cronlog maintains an accurate track of CRON's activities. A startup option is available to make CRON lock the log file during access, allowing several workstations on a network to run CRON with a central logfile on the server. CRON works well with DESQview. Under DESQview, the background operation of UNIX cron can be emulated by letting CRON run by itself in a (small) window. Indeed, CRON was originally developed for use with DESQview. See chapter 7 for instructions on using CRON with DESQview, and for information about the special CRONDV program for spawning xx-pif.dvp files. Although based on UNIX cron, CRON is developed from scratch and contains no proprietary code. CRON.EXE has been reported to work fine with Microsoft Windows 3.0, although I have not tested this. CRON User's Guide Rev. 01-20-91 (C) 1991 Tron Hvaring CRON User's Guide Rev. 01-20-91 Page 2 1.2 Shareware CRON is shareware (aka. User Supported Software). This means that you may freely use CRON for a reasonable evaluation period. You may also freely distribute CRON11.ZIP in unmodified form, to BBS'es or otherwise. If, after a reasonable evaluation period, you find CRON useful, I would appreciate a contribution. NOK 150 (USD 25) suggested. All the usual disclaimers about damages, fitness for any particular purpose and all that apply. In brief, you use CRON at your own risks and perils. The contents of the CRON16.ZIP archive are Copyright (C) 1990-1991 by Tron Hvaring. 1.3 Acknowledgements Thanks to Thomas Wagner, Berlin, Germany for his EXEC routines (public domain software, available as EXEC23.LZH on many BBS'es), on which CRON's swap logic is based, and to Borland International for their splendid debugger. Thanks to Julian Templeton, London, for suggesting the new character escape facility. 1.4 System Requirements CRON runs on any IBM PC compatible computer under the DOS operating system, version 3 or later. CRON requires a minimum of 44KB of free memory to load, more for large CRONTABS. The special version CRONDV.EXE runs on the same hardware but only under DESQview. 1.5 Feedback Your comments, suggestions and bug reports are most welcome. Since CRON implements all the features of UNIX cron that make sense in a DOS environment, new functionality is not likely to be added if not sollicited by users. Bug reports, on the other hand, is a different story. CRON User's Guide Rev. 01-20-91 (C) 1991 Tron Hvaring CRON User's Guide Rev. 01-20-91 Page 3 2 INSTALLATION 2.1 Archive Contents This archive should contain the following files: - CRON.EXE, the executable program - CRONDV.EXE, special executable for running DESQview xx-PIF.DVP files, see chapter 7. - CRON.DOC, this document - CRONTAB, annotated sample crontab - CRONTAB.DV, annotated sample crontab for CRONDV - LOGCHECK.EXE, let CRON control its log size - CDD.EXE smarter CHDIR command - READ.ME list of fixes and new features in this version 2.2 Installing CRON Copy CRON.EXE/CRONDV.EXE to a directory in the DOS PATH (e.g. c:\bin). Create a directory for CRON's use, for example C:\CRON. This directory should be used for crontabs and log files. Create your crontab using the supplied CRONTAB as a template. Read the rest of this document for more information about crontabs. Put your crontab in the directory you created. 2.3 Setting up CRON's environment CRON recognizes several environment variables. These are: CRONTAB if set, CRON assumes it contains the name of a file that is to be used as the crontab. This can be overridden on the command line. Typically, this environment variable will contain C:\CRON\CRONTAB. CRONLOG required if you want CRON to log its operations. Set to the name of the logfile (e.g. C:\CRON\CRONLOG). Note that CRONLOG must point to a fully qualified file name, including drive/path. This is required since the commands that CRON execute may change the logged drive and/or directory. TZ indirectly consulted by the time management functions of the run-time library. If you live in a country that uses daylight savings, TZ must be set for CRON to operate CRON User's Guide Rev. 01-20-91 (C) 1991 Tron Hvaring CRON User's Guide Rev. 01-20-91 Page 4 correctly when the daylight savings period changes (twice a year). Syntax is: TZ=<time zone><hours after GMT><daylight saving> where <time zone> and <daylight saving> *must* be three- character upper-case strings, and <hours after GMT> is a signed number, positive westwards and negative eastwards relative to Greenwich. The actual contents of the character strings is irrelevant -- only their presence count. A correct value for Norway is TZ=CET-1CDT whereas a correct value for the UK is TZ=GMT0GDT If your country does not practice daylight saving, omit the last string, e.g. TZ=CET-1 if Norway hadn't practiced daylight saving. TMP if CRON is run in swap mode, it will swap most of itself out of memory when executing commands. By default, CRON will swap to a temporary file in the directory named by the TMP variable, or in the current directory if the TMP directory does not exist. If you have a RAM disk with 50- 70K of free space, set TMP to the name of directory on this RAM disk. The directory used for swapping can be overridden on the command line. COMSPEC when CRON needs to spawn COMMAND.COM, it will use the name contained in this variable, which is normally C:\COMMAND.COM. Other shells, like 4DOS, can be used by setting COMSPEC appropriately. CRONPIF see chapter 7.5. This is the directory where CRONDV looks for xx-pif.dvp files to execute. Setting these environment variables allows you to start CRON with the appropriate environment by simply typing CRON. Here's a selected part of my AUTOEXEC.BAT: SET CRONTAB=d:\cron\crontab SET CRONLOG=d:\cron\cronlog SET TMP=m:\tmp SET TZ=CET-1CDT 2.4 Set Your Clock CRON will not operate as expected if the DOS date and time are not set correctly. In particular, remember to update your clock when crossing daylight savings zone boundaries. CRON User's Guide Rev. 01-20-91 (C) 1991 Tron Hvaring CRON User's Guide Rev. 01-20-91 Page 5 3 USING CRON See chapter 7 for further instructions regarding CRONDV.EXE. 3.1 Command-line Summary CRON is started as follows: CRON [option] [option] ... As a special case, entering "CRON ?" will display an option summary and terminate. The available options are: -c tab -- override CRONTAB name -n -- no log -s -- swap mode -e -- swap to LIM/EMS memory if possible -d dir -- swap directory override -v -- verbose mode -l -- lock CRONLOG when accessing if on network drive -L -- always lock CRONLOG when accessing 3.2 Crontab override -- the '-c tab' option This option overrides the name that CRON will use for the crontab. 'tab' must be the name of an existing file. Full drive/path syntax or relative syntax may be used. In the absence of this option, CRON will look for the crontab as follows: - if the CRONTAB environment variable is set, use that name - otherwise, look in the directory that was current when CRON was started for the file name "CRONTAB". CRON will complain and abort if it cannot find a crontab. Example (friday afternoon): cron -c d:\cron\weekend Note that CRON only reads the crontab at startup. CRON User's Guide Rev. 01-20-91 (C) 1991 Tron Hvaring CRON User's Guide Rev. 01-20-91 Page 6 3.3 Disable logging -- the '-n' option If CRON is set up for logging, this option disables logging. If CRON would not have logged anyway the option is ignored. Logging is only done if the environment variable CRONLOG is set to a fully qualified filename (i.e. with full drive/path syntax). CRON will complain if CRONLOG is set but does not point to a fully qualified filename. 3.4 Swap Mode -- the '-s', '-d dir' and '-e' options CRON may optionally swap most of itself out of memory when executing other commands. This feature is enabled by entering the -s option. CRON will by default swap to a temporary file, either in the TMP directory if set, or in the directory that was current when CRON was started. The -e option will make CRON try to swap itself to LIM/EMS memory, if present and available in sufficient quantities. See chapter 7 for a discussion of memory requirements. If EMS swapping is not possible, CRON reverts to disk swapping. The '-d dir' option will make CRON swap to a temporary file in the directory 'dir' instead of the standard places described above. CRON complains if it sees -d or -e but not -s, and if 'dir' is not a valid directory. 3.5 Verbose mode -- the '-v' option This option requires that an ANSI driver be present in your system, e.g. ANSI.SYS, or DVANSI.COM under DESQview. The effect of -v is that CRON maintains a real time display showing the next command scheduled for execution, the time it will be executed, and the time left (in seconds) until the command is executed. CRON User's Guide Rev. 01-20-91 (C) 1991 Tron Hvaring CRON User's Guide Rev. 01-20-91 Page 7 3.6 Locking the logfile -- the '-L' and '-l' options If one of these options is entered, CRON will lock byte 0 of the logfile before accessing it, using the DOS 3.1 locking calls. CRON uses the IOCTL Is Redirected Handle call to determine if the logfile is on a network drive. Your DOS version must support this call (DOS function 44H, subfunction 0AH) for logfile locking to work with the '-l' option. If you enter the '-L' option CRON will not check if the file is remote but will always try to lock it. This is useful if you have loaded SHARE.EXE on the local machine. Most networks support the DOS 3.1 locking calls. CRON has also been tested and found to work fine on a Novell NetWare network. If your network does not support the way CRON goes about locking the logfile, CRON will still work but will simply disable logfile locking. If a lock call fails (either because of a timeout or because you used the '-L' option and the locking call failed), CRON will print a timestamped error message and disable locking and verbose mode. 3.7 Stopping CRON CRON is stopped by typing ESC. CRON reminds you of this at startup. 3.8 Startup Information When CRON starts, it will print a banner consisting of the program name, version, copyright, memory available after CRON has processed the crontab and grabbed what it needs, and a reminder that you should hit ESC to stop CRON. If CRON believes that it runs under DESQview, it will print the additional line '(DESQview detected)'. In verbose mode, CRON will then print information about the first command to execute, and start its real-time second countdown. If this information looks funny (displaying left arrows and '[' characters) you don't have an ANSI driver resident. Put the line DEVICE=[drive:\path\]ANSI.SYS in your CONFIG.SYS file, or load DVANSI.COM before starting CRON if running under DESQview. CRON User's Guide Rev. 01-20-91 (C) 1991 Tron Hvaring CRON User's Guide Rev. 01-20-91 Page 8 4 THE CRONTAB IN DETAIL 4.1 Syntax Summary CRONTAB is a regular ASCII text file that can be created by any editor or word processor in non-document mode. Lines containing a '#' character in column 1, and blank lines, are ignored (useful for commenting crontabs). All other lines are interpreted as CRONTAB ENTRIES. A CRONTAB entry has the following format: minute hour day month day-of-week command Fields are separated by any number of tabs or spaces. No tabs or spaces are allowed inside the first 5 fields. Maximum line length is 512 characters including the trailing CR/LF pair. 4.2 The Date and Time fields These fields can have the following forms: * all legal values i,j,k sequence of values i-j inclusive range of values The sequence and range forms may be combined, as in 1,3,5,7-9,11,13-17,19 An asterisk '*' overrides any other value in a field. Thus 1,3,*,5,7 is equivalent to * Legal ranges for the different fields are as follows: minute -- 0..59 hour -- 0..23 (24-hour clock) day -- 1..31 (must be consistent with month) month -- 1..12 day-of-week -- 0..6, 0 = Sunday, 1 = Monday etc. CRON detects values that are out of range, and impossible dates (like February 31.). CRON User's Guide Rev. 01-20-91 (C) 1991 Tron Hvaring CRON User's Guide Rev. 01-20-91 Page 9 The actual execution times computed by CRON is the largest matching set of times. This is best explained by the following example: 54 6 1,15 * 1 doreport means that the command 'doreport' will be executed at 06:54 on the 1. and 15. of every month (month = '*'), AND on each monday (day-of-week = 1). If the 1. or 15. falls on a Monday, 'doreport' will not be executed twice. The extremes in terms of periodicity are: * * * * * dooften -- executes 'dooften' every minute 1 0 1 1 * calendar -- executes 'calendar' at 00:01 each January 1. 4.3 The Command Field The 'command' field of a CRONTAB entry consists of one or more COMMAND LINES, separated by semicolons ';'. If the command field contains only one command line, it should not be terminated by a semicolon. A COMMAND LINE obeys the following syntax: [~][!]DOS command line i.e. an optional '~' character, followed by an optional '!' character, followed by a regular DOS command line. Thus a command field looks like [~][!]command line;[~][!]command line;[~][!]command line.... or [~][!]command line The '~' character means 'NOSWAP'. It means that CRON should not swap itself out when executing this command, even if swapping is enabled. If swapping is disabled, the character is ignored. This feature is useful for small commands that require modest amounts of memory. If both '~' and '!' are entered, '~' must precede '!'. CRON User's Guide Rev. 01-20-91 (C) 1991 Tron Hvaring CRON User's Guide Rev. 01-20-91 Page 10 IMPORTANT NOTE: --------------- if any 'command line' contains path separator characters (i.e. '\' inside pathnames) each '\' must be entered TWICE. This is because starting with V1.6, CRON assumes that '\' is an escape character, causing the next character to be processed literally (even if it is a '!', a '~' or a ';'). Thus cdd d:\mypath will not work as expected, whereas cdd d:\\mypath will. The '!' character is a synonym for %COMSPEC% /C, i.e. the contents of the environment variable COMSPEC, followed by the string " /C ". Thus the command lines !dir and COMMAND /C dir are equivalent, provided COMSPEC points to COMMAND.COM. '!' (or its synonym) is *required* for COMMAND.COM internal commands, like DIR, DEL and CD. '!' (or its synonym) is optional for executable programs, including .BAT files. If your command uses redirection (i.e. <, >, >> or |), '!' is required since redirection is handled by COMMAND.COM. Otherwise it should not be used, as it adds no functionality except consuming a few K of additional memory. Thus the command line sort <infile >outfile will not work as expected, but !sort <infile >outfile will. CRON User's Guide Rev. 01-20-91 (C) 1991 Tron Hvaring CRON User's Guide Rev. 01-20-91 Page 11 Note that CRON knows about .BAT files and will spawn COMMAND.COM internally for them. Therefore, the '!' prefix is not needed for .BAT files. When locating the command to execute, CRON follows the standard DOS algorithm: first look in the current directory, then in each directory along the PATH, respecting the search order for .COM, .EXE and .BAT files. Thus CRONTAB command lines may be entered exactly as if you were at the DOS prompt, except for the '!' prefix (which is implicit when at the DOS command line). CRON sets the logged drive and directory to their startup values (i.e. the drive and directory that were current when CRON started) before executing a CRONTAB entry. If an entry contains multiple command lines, the logged drive and directory are not reset between command lines. This allows entries such as: 57 5 1,15 * * ~!d:;~!cd \\acct\\dbase;misreport assuming that the program 'misreport' expects to be run from the 'D:\ACCT\DBASE' directory. The enclosed file CRONTAB contains several commented CRONTAB entries. See chapter 9 for a description of the enclosed utilities that are useful in CRONTAB entries. CRON User's Guide Rev. 01-20-91 (C) 1991 Tron Hvaring CRON User's Guide Rev. 01-20-91 Page 12 5 THE CRONLOG IN DETAIL 5.1 General Description The optional CRONLOG is a text file produced by CRON where all its operations and their results are logged. CRONLOG is a plain ASCII text file with highly structured lines. Cronlogs are suitable for automatic processing, for example with AWK or similar utilities. The cronlog is always opened in APPEND mode, so it is ever-increasing. The utility LOGCHECK.EXE (documented later) can be used to control the size of the cronlog. CRON produces a log entry when: - CRON is started - CRON is stopped - CRON starts to execute a CRONTAB entry - CRON has finished to execute a CRONTAB entry - CRON starts to execute subsequent command lines in a multi- command entry - CRON has finished to execute a command line in a multi-command entry. Entries have the following general format: <entry token> <operation> <date and time> <additional data> 5.2 Starting And Stopping CRON These lines are as follows: !cron started at Fri Oct 19 13:22:35 1990 !cron stopped at Fri Oct 19 13:22:51 1990 No further comments should be necessary. CRON User's Guide Rev. 01-20-91 (C) 1991 Tron Hvaring CRON User's Guide Rev. 01-20-91 Page 13 5.3 Start and Stop of CRONTAB Entry Processing When CRON starts executing a CRONTAB entry, it produces a log record starting with the character '>'. A typical entry is as follows: > 'mapmem -v' Fri Oct 19 13:43:00 1990 meaning that the command field 'mapmem -v' started to execute on the indicated date and time. When the command returns, CRON produces a log entry starting with the '<' character, as follows: < 'mapmem -v' Fri Oct 19 13:43:00 1990, rc = 0 meaning that the command 'mapmem -v' executed until the indicated date and time (in this example, for less than 1 second), and returned with an exit code 0 ('rc = 0'). CRON User's Guide Rev. 01-20-91 (C) 1991 Tron Hvaring CRON User's Guide Rev. 01-20-91 Page 14 5.4 Logging Multi-Command Execution For CRONTAB entries containing multiple command lines, CRON produces a sequence of records bracketed by a '>' entry, marking the start of the entry as a whole, and a '<' entry, marking the end of the entry as a whole. Between these entries, a pair or '>>' (start of command) and '<<' (end of command) is produced for each command line in the entry, including the first. The text of the '>' and '<' entries contain the entire command field. The text of the '>>' and '<<' entries contain the individual command lines, *without* any '!' or '~' prefix. These prefixes appear in the bracketing lines, though. A sample sequence is shown below, corresponding to the CRONTAB entry 54 16 * * * !d:;!cd \\cron;mapmem -v > '!d:;!cd \cron;mapmem -v' Fri Oct 19 16:54:00 1990 >> 'd:' Fri Oct 19 16:54:00 1990 << 'd:' Fri Oct 19 16:54:00 1990, rc = 0 >> 'cd \cron' Fri Oct 19 16:54:00 1990 << 'cd \cron' Fri Oct 19 16:54:00 1990, rc = 0 >> 'mapmem -v' Fri Oct 19 16:54:00 1990 << 'mapmem -v' Fri Oct 19 16:54:01 1990, rc = 0 < '!d:;!cd \cron;mapmem -v' Fri Oct 19 16:54:01 1990, rc = 0 Exit codes are only produced for '<' and '<<' entries. See the next chapter for a discussion of how to interpret these codes. Some '<' and '<<' entries may contain the string "*** FAILED ***". This means that an error occured. See the next chapter for an interpretation of such entries. In a bracket '<' line, the 'rc = n' field has the same value as the last sub-command that was executed. CRON User's Guide Rev. 01-20-91 (C) 1991 Tron Hvaring CRON User's Guide Rev. 01-20-91 Page 15 6 ERROR HANDLING 6.1 General Considerations Errors may occur for several reasons: - CRON does not have enough resources to run - CRON may be unable to locate or spawn a command - a critical error can hit CRON (logfile disk full, swap error) - the spawned command can fail - a critical error can hit a spawned command - a spawned command may encounter an internal exception requiring user intervention (i.e. the command prompts for keyboard input). If a critical error occurs -- either inside CRON or in a spawned command -- you are simply out of luck, since the infamous 'Abort, Retry, Ignore' requires user intervention (i.e. keyboard input). I considered trapping critical errors within CRON, but decided against it. Since CRON is typically run on an unattended system, and since CRON cannot know whether or not a spawned command has put the system into an unstable state, we cannot be quite sure that a 'disk full' error really means that the disk is full. To prevent disaster we simply let the standard DOS error handling take over, suspending everything until a human can take over. This is also known as the 'better safe than sorry' strategy. CRON relies on the fact that a spawned command will eventually return. If the command decides it wants keyboard input, and no one is around, CRON will be suspended until someone comes around to hit the keyboard. The net effect of a critical error hitting a spawned command is the same. The bottom line is that you should make sure no critical errors will occur when leaving CRON in charge of an unattended system. Specifically, make sure that all required peripherals are online, that any addressed printers are online and have enough paper, et cetera, et cetera. Also, make sure that spawned commands are started in such a way that they won't ever require keyboard input. Perhaps one day I'll understand what is so critical about a printer being out of paper, and why that condition is handled in the same way as a hard disk CRC error. Or perhaps I won't. CRON User's Guide Rev. 01-20-91 (C) 1991 Tron Hvaring CRON User's Guide Rev. 01-20-91 Page 16 6.2 Failure to Spawn a Command CRON may fail trying to spawn a command. This is reflected by a log entry of the '<' or '<<' variety, with 'rc = -1'. If swapping is not enabled, an additional 'errno = n' is appended to the entry. See chapter 8 for interpretation of errno values. If swapping is enabled, 'rc = -1' always means that CRON could not locate the executable file. This may be caused by: - you forgot to prefix a COMMAND.COM internal command with '!' - the command does not exist in the current directory, nor in any directory in the current PATH. If a command name is given without an extension, CRON will try .COM, .EXE and .BAT exactly like COMMAND.COM does. If a '!' style command returns an exit code of -1, it means that the command interpreter itself failed to load. This is normally a serious condition, with possible causes: - the command named by COMSPEC has disappeared or is no longer in the DOS PATH - the COMSPEC environment variable has been corrupted - the PATH environment variable has been corrupted If swapping is not enabled, 'errno' contains further information. If swapping is enabled, one of the three causes above apply. 6.3 A Spawned Command Fails This is indicated by an exit code in the range 0..255. It means that CRON could spawn the command, and that the command itself returned a non-0 exit code when issuing the DOS TERMINATE call. CRON's actions depend on whether or not the current entry contains multiple commands. If the command was the only command in the CRONTAB entry, CRON simply records the exit code in the log (if enabled) and proceeds to schedule the next command. The philosophy behind this is that a failure in one crontab entry should not influence the operation of other, possible unrelated, crontab entries. If the command was part of a multi-command entry, CRON assumes that all commands in the entry are somewhat interdependent and therefore aborts execution of remaining commands in the entry, logging this fact if logging is enabled. CRON User's Guide Rev. 01-20-91 (C) 1991 Tron Hvaring CRON User's Guide Rev. 01-20-91 Page 17 The CDD.EXE utility (documented in a later chapter) is a more intelligent alternative to COMMAND.COM's builtin CHDIR command. The crontab entry 38 04 * * * ~cdd d:\\acct\\dbase;misreport will first change the logged drive and directory to 'D:\ACCT\DBASE', without swapping CRON, and then execute the command 'misreport'. Since 'misreport' obviously wants to be run from this drive/directory, we had better not run it if the 'cdd' command fails. So, if cdd returns a non-0 exit code, 'misreport' is skipped and CRON proceeds to schedule the next entry after logging the failure. 6.4 Other Internal CRON errors If a swap file error occurs, CRON will report an error code of 256 (rc = 256) for the appropriate '<' or '<<' entry and will disable swapping for all commands thereafter. This may cause failure of other commands that need so much memory that they cannot coexist with CRON in memory. Error codes starting from 768 and upwards are specific to the swapping interface to the EXEC function, and are documented later. 6.5 Exit Codes and COMMAND.COM COMMAND.COM is too dumb to return the exit code of a command that it spawns, even with the /C switch. Thus, when CRON executes a '!' entry or a .BAT file, it will receive an exit code 0 provided COMMAND.COM itself could be spawned, but the exit code from the actual command is lost even if it was non-0. Thus the following crontab entry may give surprising results: 12 7 * * * !z:;!cd \\absent;!XXXXXXXXXXXXX CRON will happily spawn all three commands, since spawning COMMAND.COM succeeds. COMMAND.COM will print something like 'Bad command or file name', but will still return an exit code of 0. Thus all three commands -- which failed -- show up with 'rc = 0' in the cronlog, since COMMAND.COM lies about the results. 4DOS or some other more intelligent shell may handle this in a better way. For multi-command entries where changing drive and path is crucial, use the supplied CDD.EXE utility instead of "!d:;!cd \\path" constructs. CRON User's Guide Rev. 01-20-91 (C) 1991 Tron Hvaring CRON User's Guide Rev. 01-20-91 Page 18 7 ADVANCED TOPICS 7.1 Resource Requirements CRON requires 44 KB of memory, plus up to 1K per 16 crontab entries. The number of crontab entries should be rounded up to the nearest multiple of 16. This is a worst-case estimate; most CRONTAB entries require less than 64 bytes. When swapping, CRON leaves 1.1K of itself -- plus the size of its environment -- in memory, swapping out the rest. When swapping to disk, CRON therefore needs (size of resident CRON - 1.1K + pad to cluster boundary + directory overhead) bytes of disk space, typically less than 64K bytes. When swapping to EMS, CRON requires (size of resident CRON - 1.1K + pad to nearest 16K boundary) bytes, typically 3 pages = 48K bytes. For very large CRONTABS (several hundred entries) CRON may require 4 EMS pages, i.e. 64K bytes. When swapping to disk, the swap file is closed before spawning. The spawned command thus has a full 20 handles available. When swapping to EMS, CRON uses 1 EMS handle which is kept across the EXEC call. CRON only needs EMS and disk space when a spawned command is actually executing. Between commands (i.e. when CRON is waiting for the next command to execute), no EMS or disk space is used. CRON hooks no interrupt vectors except those hooked by the run-time library, and does not use floating point. 7.2 Using CRON with DESQview CRON works very well with DESQview. If you use DESQview, chances are that you have EMS in your system. If so, use the -s -e options to CRON for best results. CRON detects DESQview at startup. When executing its idle loop (i.e. waiting to execute the next command), CRON issues the 'give up time slice' DESQview API call. (In command line operation, CRON issues Int 28H calls instead). CRON User's Guide Rev. 01-20-91 (C) 1991 Tron Hvaring CRON User's Guide Rev. 01-20-91 Page 19 CRON is generally well behaved: all output is via DOS, input is via BIOS keyboard calls. Does not use floating point, can (should!) run in the background, does not use serial lines, does not require a floppy disk. Note that CRON should not be swapped out by DESQview, because of its real-time nature. Having DESQview swap CRON would invalidate CRON's timing function. So, when designing a DESQview profile for CRON, you should think more about the programs you are spawning from CRON than about CRON itself. For example, if you spawn a telecommunications program (which is a natural for CRON), you should tell DESQview about which port it uses. Also, if a spawned program needs EMS memory, the amount should be ADDED to amount required by CRON if CRON is swapping to EMS. The previous subsection states the memory resources needed by CRON in its different operational modes. These should be added to whatever is required by spawned programs. See also section 7.5 for the DESQview specific version of CRON. 7.3 CRON Technical Information CRON is written in C and assembler and compiled with Turbo C++ (ANSI C compiler mode) and TASM 2.0. The Compact memory model is used, allowing an unlimited CRONTAB size subject to memory constraints. Because of the way Turbo C sets up DGROUP, CRON actually uses LESS memory in the Compact model than in the Small model, for crontabs up to 2-300 entries. The CRON source code is around 2500 lines, including comments. CRON uses only documented DOS and BIOS calls. All EMS access is via interrupt 67H, using the approved methods to detect the presence of an EMS manager. 7.4 Differences between CRON and UNIX cron There are two major differences between CRON and UNIX cron: - UNIX cron runs in the background - UNIX cron executes commands concurrently, while CRON executes commands sequentially. Under UNIX, two commands can be started by cron at the same time (well, almost). Under DOS, two commands scheduled to execute at the same time will execute one after the other, and the order of execution is random. CRON User's Guide Rev. 01-20-91 (C) 1991 Tron Hvaring CRON User's Guide Rev. 01-20-91 Page 20 Since UNIX cron runs in the background, and concurrently with the commands it spawns, a spawned command can never suspend cron. As described above, this may well happen with CRON in some cases. The background nature of UNIX cron can be emulated to some extent by running CRON under DESQview. Concurrency it not possible, however. With CRON, a command can be delayed if the previous command executes for a long time, i.e. past the time that the next command was due to execute. All commands will be executed, though. UNIX cron always starts commands at the scheduled times. Some of the more esoteric fields of the UNIX cronlog have been skipped, such as PID's of commands. The UNIX 'crontab' utility is of limited use under DOS and is not implemented. The LOGCHECK.EXE utility performs about the same actions as the UNIX /etc/logchecker shell script. UNIX cron reads all files in the /usr/spool/cron/crontabs directory as crontabs when it starts up -- this is the central repository of all user's crontabs. Since DOS's multiuser capability is somewhat limited, this feature was not deemed necessary. Also, hard-coded directory names and excessive use of environment variables are not popular in DOS circles. UNIX cron writes its logfile in the /usr/lib/cron directory. CRON's logfile is defined by the CRONLOG environment variable. UNIX cron re-reads its crontabs at run time if a crontab is modified by the 'crontab' utility. With CRON, you stop CRON, modify the crontab and restart CRON to achieve the same effect. The command-line options to CRON are not available nor useful under UNIX. The '~' and '!' command prefixes are specific to CRON and are not available (nor meaningful) with UNIX cron. CRON User's Guide Rev. 01-20-91 (C) 1991 Tron Hvaring CRON User's Guide Rev. 01-20-91 Page 21 7.5 CRONDV.EXE 7.5.1 What Is CRONDV.EXE? CRONDV.EXE is new with version 1.6 of CRON. It can only be used with DESQview. The CRONTAB used with CRONDV.EXE should only contain two- letter commands, optionally prefixed with a drive:\\path\\, corresponding to the two letters used to start a program from the DESQview menu. 7.5.2 How it Works CRONDV will use the DESQview API to spawn the corresponding programs asynchronously. The advantages are: - CRONDV may run in a minimal (~ 40 K) window, since it doesn't spawn other processes in its own window - for multiple-command CRONTAB entries, the commands will start simultaneously and run in parallel (in the DESQview sense) - the xx-PIF.DVP files may be modified without the need to modify the CRONTAB The disadvantages are: - CRONDV can *only* run xx-PIF.DVP files, *not* regular programs - since CRONDV uses the "Sleep" API call, the real-time display is not available - the CRONLOG will not (in fact, cannot) show return conditions of the spawned programs, since CRONDV doesn't wait for their return 7.5.3 The CRONPIF Environment Variable CRONDV looks for an additional environment variable called CRONPIF. If present, any non-prefixed two-letter command is assumed to refer to an xx-PIF.DVP file in the directory named by CRONPIF. If CRONPIF is not set, CRONDV assumes C:\DV by default. For example, suppose you have SET CRONPIF=D:\MYPIFS then the CRONTAB entry 2317 * * * RE will make CRONDV try to execute D:\MYPIFS\RE-PIF.DVP at 17:23 daily, just as if you had entered RE under the Open Window option on the DESQview menu. CRON User's Guide Rev. 01-20-91 (C) 1991 Tron Hvaring CRON User's Guide Rev. 01-20-91 Page 22 On the other hand, the CRONTAB entry 2317 * * * d:\\specials\\re will execute D:\SPECIALS\RE-PIF.DVP regardless of the contents of CRONPIF. 7.5.4 CRONLOG entries CRONDV only produces the '>' and '>>' flavours of CRONLOG entries, since it is not possible for CRONDV to detect when commands terminate. 7.5.5 About Programs spawned by CRONDV CRONDV runs programs as if they were started by the two-letter sequences of the DESQview menu. This means that CRONDV does not control whether or not the programs close their window on exit. The xx-PIF.DVP's used with CRONDV should be set up with unattended execution in mind, so that you don't end up with lots of windows waiting for EXIT to be typed. CRONDV cannot control nor detect whether or not the programs could be started. Lack of memory, resource conflicts (e.g. two comm programs trying to use the same modem simultaneously) etc. goes undetected and unreported. It is your responsibility to make sure that these things do not cause trouble. 7.5.6 Command-line Options CRONDV supports the following subset of the CRON command-line options: -c tab -- CRONTAB override -n -- no logfile -l -- logfile locking for network logfiles -L -- unconditional logfile locking -v -- limited verbose mode See the corresponding section for CRON.EXE for further details. The -v option will make CRONDV print the name of the PIF file and the time of execution of the command each time CRONDV starts to wait for the next command to execute. There is no real-time display, so DVANSI.COM is not required. CRON User's Guide Rev. 01-20-91 (C) 1991 Tron Hvaring CRON User's Guide Rev. 01-20-91 Page 23 8 REFERENCE SECTION 8.1 Error Messages CRON can complain about various things, at startup and later. All error output is sent to stdout (i.e. DOS handle 2). Any startup error, and some other errors, make CRON terminate. The following list describes the errors (in no particular order): cdd("dirname") failed CRON failed to do an internal drive/directory change. Usually means disk failure, or a spawned command has wreaked havoc in your system. This error can occur after each spawned command. No memory for crontab CRON failed to allocate dynamic memory for loading the crontab. This means that your crontab is *very* large or that you have very little memory in your system. 'command' : illegal date The crontab entry containing 'command' specifies an illegal date, for example February 31. Correct the crontab entry. Syntax: 'entry' The crontab line containing 'entry' does not conform to crontab entry syntax rules. Correct the offending line. CRONTAB is empty No entries were found in crontab. 'file': cannot open CRON could not open the named file. File probably does not exist. 'name': not a directory The specified 'name' is not a directory (swap mode). CRON User's Guide Rev. 01-20-91 (C) 1991 Tron Hvaring CRON User's Guide Rev. 01-20-91 Page 24 Unable to locate CRONTAB Either the file name pointed to by the CRONTAB environment variable is invalid, or the file "CRONTAB" was not found in the startup directory. 'CRONLOG=name' : not fully qualified The environment variable CRONLOG contains a name that is not a fully qualified filename. 'CRONLOG=name' : cannot open CRON was unable to open the file named by the CRONLOG environment variable. Either the file exists and is read-only, or the name specifies a directory, or the network denied create or write access to the file. (DESQview detected) Not an error message, but a startup message stating that CRON believes that it is running under DESQview. DESQview not found CRONDV was started outside DESQview '[d:\path\]xx-PIF.DVP' : not found CRONDV did not find the specified .DVP file. Lock failure @ <timestamp> A lock() call on the logfile failed, either because locking is not supported and you used the -L option, or because the call timed out. CRON[dv] continues to run, but switches off logging and verbose mode, so that the message remains on the screen. 8.2 Exit Codes Some exit codes (shown in the cronlog as 'rc = nn') have slightly different interpretations when running CRON in swap or non-swap mode. 8.2.1 Common Exit Codes All exit codes in the range 0..255 are actual exit codes from spawned commands. Their interpretation is specific to each actual command. CRON does not attempt to interpret these codes except that in a multi- command entry, the remaining commands in the entry will be skipped if a command returns a non-0 exit code, as explained earlier. CRON User's Guide Rev. 01-20-91 (C) 1991 Tron Hvaring CRON User's Guide Rev. 01-20-91 Page 25 8.2.2 Swap Mode In swap mode, interpret exit codes as follows: -1 named command not found. Either the command is actually non-existent, or you forgot to prefix a COMMAND.COM internal command with '!' 0..255 see 8.2.1 256 swap file error. CRON switches swapping off permanently and continues execution. 770 DOS EXEC: file not found 771 DOS EXEC: path not found 772 DOS EXEC: too many open files 773 DOS EXEC: access denied 776 DOS EXEC: not enough memory to load command 778 DOS EXEC: environment is corrupt 779 DOS EXEC: bad format for .EXE file (.EXE file is corrupt) 8.2.3 Non-Swap Mode In non-swap mode, interpret exit codes as follows: -1 spawn failure, errno gives further information 0..255 see 8.2.1 For -1, errno can take one of the following values: 2 ENOENT: path or file not found 8 ENOMEM: not enough memory to spawn command 19 EINVAL: illegal argument 20 E2BIG: argument list is too long 21 ENOEXEC: .EXE file format error 8.2.4 RC = -1 for '!' Commands If a command prefixed with '!' returns with 'rc = -1', it means that CRON was unable to spawn the command interpreter, i.e. the program named by the COMSPEC environment variable. This is a serious error. Some possible causes are: - the COMSPEC environment variable has been corrupted - the PATH has been corrupted - the program named by COMSPEC (e.g. C:\COMMAND.COM) has disappeared. Look out for viruses. - not enough memory to spawn command interpreter. CRON User's Guide Rev. 01-20-91 (C) 1991 Tron Hvaring CRON User's Guide Rev. 01-20-91 Page 26 9 UTILITY PROGRAMS 9.1 CDD.EXE CDD (for "change drive and directory") is a smarter replacement for DOS's CHDIR (CD) command. Since CDD is an .EXE file, it will return an exit code != 0 if it was unable to switch drive and/or directory. USE: cdd [d:][\path] Exit codes: 0 -- success 1 -- could not switch drive 2 -- could not change directory 3 -- bad command line syntax CDD is small, so I recommend using the '~' command prefix when using CDD in crontabs. Typing "CDD ?" gives a command syntax reminder. 9.2 LOGCHECK.EXE CRON usually produces large logfiles. To avoid excessive log sizes, put a call to LOGCHECK in your crontab, with a period depending on how much you use CRON and the execution frequency of your crontab entries. USE: logcheck [-s maxsize] [-L|-l] where 'maxsize' is the decimal number of kilobytes that you want your logfile not to exceed. If no 'maxsize' is entered, LOGCHECK assumes a value of 32. Use -L or -l if you want LOGCHECK to lock the logfile when it operates (similar to CRON's -L and -l options). If LOGCHECK finds that your current cronlog exceeds 'maxsize' it will perform the following actions: -- copy the current cronlog to a file with the same name but with extension 'old'. For example, if your cronlog is named 'CRONLOG.CUR', its current contents will be copied to 'CRONLOG.OLD'. If your cronlog is named 'CRONLOG.OLD', the copy will be named 'CRONLOG.OL2'. Any existing file with the modified name will be destroyed. The copy is made in the same directory as the cronlog. -- truncate the cronlog to 0 size, then add the following entry: '!logswap <timestamp>'. CRON User's Guide Rev. 01-20-91 (C) 1991 Tron Hvaring CRON User's Guide Rev. 01-20-91 Page 27 The following crontab entry will check your network cronlog daily, making sure it doesn't become much larger than 64K: 13 5 * * * ~logcheck -s 64 -l Exit codes from LOGCHECK: 0 -- successful log swap 1 -- no action (log smaller than maxsize) 2 -- could not swap log (disk error, access denied) 3 -- CRONLOG environment variable not found. 4 -- bad command line syntax Typing "LOGCHECK ?" gives a command syntax reminder. Caveat: LOGCHECK can only check the log when it is activated. Thus between invocations, the log can grow to a size much larger than 'maxsize' if there is a lot of CRON activity going on. Select LOGCHECK periodicity according to your crontab. CRON User's Guide Rev. 01-20-91 (C) 1991 Tron Hvaring CRON User's Guide Rev. 01-20-91 Page 28 10 PROGRAM HISTORY Version Date Comments ----------------------------------------------------------------------- 0.0 - 1.0 10-19-90 [Internal] Internal versions 1.1 10-20-90 [Public] First public release 1.2 10-21-90 [Internal] Benign bug fixed: in the absence of the -L option, a file handle was needlessly kept open permanently. Harmless, but wasteful. Also, CRON.DOC stated that CRON would swap to the current directory if no TMP variable and if no -d option. This is wrong. CRON will swap to the directory that was current when CRON started under these conditions. LOGCHECK.EXE always unlocked the logfile even if locking was not specified. 1.3 10-26-90 [Internal] Upgrade to T. Wagner's EXEC23 -- swap file is now closed when spawning. Saves a file handle. 1.4 10-26-90 [Public] Added compile date to CRON's banner. 1.5 01-15-91 [Internal] Added the character escape facility as suggested by Julian Templeton. 1.6 01-20-91 [Public] Now includes CRONDV.EXE, DESQview specific version for spawning xx-PIF.DVP's. New locking options, -l and -L, for finer control. All .EXE's now have the same version number (1.6). CRON User's Guide Rev. 01-20-91 (C) 1991 Tron Hvaring